Avoid
.rst
extensions for files designed to be read directly (such asREADME.rst
).If the file declares file format in the vim modeline (e.g.
vim:ft=rst
), GitHub no longer requires the extension to render the file correctly.Avoid
.txt
extensions for files designed to be read directly.doc/README
should briefly describe the project.There should be
README
→doc/README
symlink.The
README
symlink should not shipped in release tarballs.Validate reStructuredText documents with
rst2xml --strict
.Validate POD documents with
podchecker
.DocBook XML documents should be avoided.
Validate legacy DocBook XML documents with
xmllint --valid
.Check URLs using urlycue.
Check that version numbers in documentation and in the code match.
Manual pages should include version numbers.
Manual page dates should be up-to-date.
English manual page dates should be in the YYYY-MM-DD format. Manual pages must not use a middle-endian date format.
In manual pages:
- apostrophes should be written as
'
, not\(aq
; - hyphens should be written as
-
; - minus-signs should be written as
\-
.
- apostrophes should be written as
rst2man
calls should use--input-encoding=UTF-8
.Built manual pages should not include vim modelines.
Check that the changelog is complete.
In repo, there should be top-level
LICENSE
(orCOPYING
) file.In release tarballs,
LICENSE
(orCOPYING
) should be moved to thedoc
subdirectory.Copyright notices should be up-to-date.
GPLv2 files should carry the following license notice:
This file is part of PROJECT.
PROJECT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.
PROJECT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Autoconf-based packages should provide the
private/autogen
andprivate/autoclean
scripts.The name of Autoconf configuration header files should be
autoconf.h
(or similar).autoconf
should fail when 3rd-party macros are missing, e.g.:m4_pattern_forbid( [^PKG_CHECK_MODULES], [undefined macro PKG_CHECK_MODULES; install pkg-config and run private/autogen] )
Check if all the files (binaries, manual pages) are installed correctly.
- Use
perl -pi
(rather thansed -i
) for in-place edits. - Don't assume
install
is GNU install. Don't useinstall -D
because GNU install does something entirely different that FreeBSD install. - Makefiles can require GNU make, but then they should fail with helpful error when run against BSD make.
- Check Python code with pydiatra.
- Check Python code with pyflakes.
- Check Python code with pylint.
- Python modules should have sensible
__all__
. - Validate module long description with
rst2xml --strict
. - Don't assume that the Python interpreter is at
/usr/bin/python
. setup.py
should not import any code from the source tree.- Check Python version at runtime.
- Check Python version at install time.
- Byte-compile source at install time.
- Check Perl code with perlcritic.
- Every Perl script should start with
no lib '.';
as a defence against CVE-2016-1238. - Don't assume that the Perl interpreter is at
/usr/bin/perl
.
- Check shell scripts with shellcheck.
- Shell scripts should use
set -e
. - Shell scripts should use
set -u
. - Use
command -v
, notwhich
.
- LFS build flags should be enabled.
- Environment variables such as
CC
,CFLAGS
, etc. should be honored. CFLAGS
should be honored when linking (so that-fsanitize=address
etc. work).- Check code with cppcheck.
- Use
tiparm()
instead oftparm()
.
The
--version
option should print to stdout, not stderr.Note that in Python prior to 3.4,
argparse
doesn't do it correctly out of the box: https://bugs.python.org/issue18920The
--version
option should print versions of most important underlying libraries.Exit status for
--version
should be 0.The
--help
option should print to stdout, not stderr.Exit status for
--help
should be 0.Programs that produce copious amount of output (and do nothing else besides that) should have default signal handler for
SIGPIPE
.Programs should catch exceptions that could be caused by typical user or environment errors (e.g., a file cannot be opened).
There should be command-line option to let these exceptions go through.
- Coverage file should be up to date.
- There should be an easy way to run the tests against installed package.
- Files should have sane ownership (
root:root
) and permissions (0644 or 0755). - Directory entries should be sorted.
(For GNU tar, use
--sort=name
.) - The POSIX 1003.1-1988 (ustar) format should be used.
- Tarballs should be compressed with
gzip -9n
. - XZ compression can be used if it would save at least 64 KiB.
- For XZ compression, the least memory-intensive preset that still offers
optimal file size should be used. The
-e
option should be used.
- Most items in
.gitignore
and.gitattributes
should be anchored with/
.
- When possible, the above checks should be automated using CI.